URLOpen

Opens a URL and starts an asynchronous download or upload operation.

OSStatus URLOpen (
                     URLReference urlRef,
                     FSSpec* fileSpec,
                     URLOpenFlags openFlags,
                     URLNotifyProcPtr notifyProc,
                     URLEventMask eventRegister,
                     void* userContext);

urlRef

A reference of type URLReference that specifies the URL you want to open. Call URLNewReference to create urlRef .

fileSpec

A pointer to a structure of type FSSpec that identifies the file to which data is to be downloaded or from which data is to be uploaded, or NULL . The fileSpec parameter must be a file specification for upload operations.

When fileSpec is a file specification, URLOpen automatically starts and completes the transfer of data between the URL specified by the urlRef parameter and the specified file. Your application will not receive data-related events, will not have access to buffer state information, and cannot call URLGetBuffer , URLGetDataAvailable , or URLReleaseBuffer .

If you specify NULL for a download operation, your application must call URLGetBuffer to retrieve the data as it is downloaded.

When fileSpec is a file specification that specifies a file that exists and you want to replace it, specify the path to the destination file, terminate the path with a slash (/), and specify kURLReplaceExistingFlag in the openFlags parameter. If you specify a name that already exists on the server and you do not specify kURLReplaceExistingFlag in the openFlags parameter, URLOpen returns the error kURLDestinationExistsError . If you do not specify a name, you do not specify kURLReplaceExistingFlag , and the name already exists on the server, the URL Access Manager creates a unique name by appending a number to the original name before the extension, if any.

For more information about the FSSpec structure, see Inside Macintosh: Files .

openFlags

A value of type URLOpenFlags Open Flag Constants that specifies data transfer options. The following constants can be used to specify download options:

kURLReplaceExistingFlag kURLExpandFile Flag kURLDisplayAuthFlag kURLDoNotTryAnonymousFlag

To specify an upload operation, set kURLUploadFlag in openFlags . You may also want to set one or more of the following constants to specify upload options:

kURLReplaceExistingFlag kURLBinHexFile Flag kURLDisplayAuthFlag kURLDoNotTryAnonymousFlag

See Open Flag Constants for descriptions of these constants.

notifyProc

A pointer to an application-defined event notification routine as described in Notification Callback Routine or NULL . If you provide this parameter, your event notification routine is called each time one of the events specified in the eventRegister parameter occurs.

If your application does not provide an event notification routine, set notifyProc to NULL . To get status information you can periodically call URLGetCurrentState to monitor the data transfer.

eventRegister

A value of type URLEventMask that specifies the events for which your application-defined notification routine should be called. See Event Constants for a description of the possible values.

userContext

An untyped pointer to arbitrary data that the URL Access Manager will pass to your notification callback routine when it is called.

function result

A result code. For a list of possible result codes, see Result Codes .

DISCUSSION

The URLOpen function starts an asynchronous download or upload operation and returns immediately. If the fileSpec parameter is a valid file specification, the URL Access Manager continues to transfer data until the transfer is complete.

To upload data, the fileSpec parameter must be an FSSpec structure.

To download data, the fileSpec parameter can be an FSSpec structure or NULL . If fileSpec is NULL , URLOpen starts the data transfer, but your application must call URLGetBuffer URLGetBuffer to complete the data transfer.

When URLOpen downloads data from a file:/// URL, the data fork is downloaded but the resource fork is not downloaded.

WARNING

Once you call URLOpen with urlRef , you cannot use the same urlRef to call URLOpen again, or to call URLDownload or URLUpload . If you need to call URLOpen , URLDownload , or URLUpload with a urlRef that has already been used for one of these calls, you need to create a new URL reference by calling URLNewReference .